package vfs.obj.entity;

import vfs.except.VFSException;
import vfs.filter.VFSFilter;
import java.util.Date;

/**
 * A VFSEntityFactory provides facilities for creating, restoring, and
 * removing various entities in the virtual folder system.
 * 
 * @author Matthew Eavenson <durandal@uga.edu>
 */
public interface VFSEntityFactory {
    
    /**
     * Creates new user with the specified id.  This
     * method makes a call to the underlying persistence
     * layer in order to make a new record in the storage 
     * medium.
     * 
     * @param uid the user's id in an external authentication system
     * @return a new user, with the specified id
     */
    VFSUser createUser(String uid) throws VFSException;
    
    /**
     * Creates new group with the specified name.  This
     * method makes a call to the underlying persistence
     * layer in order to make a new record in the storage 
     * medium.
     * 
     * @param name the group's name
     * @return a new group, with the specified name
     */
    VFSGroup createGroup(String name) throws VFSException;
    
    /**
     * Creates new node type with the specified name and description.  
     * This method makes a call to the underlying persistence
     * layer in order to make a new record in the storage medium.
     * 
     * @param name the node type's name
     * @param description the node type's description
     * @return a new node type, with the specified name and description
     */
    VFSNodeType createNodeType(String name, String description) throws VFSException;
    
    /**
     * Creates new node with the specified properties.  This
     * method makes a call to the underlying persistence
     * layer in order to make a new record in the storage 
     * medium.
     * 
     * @param name the node's name
     * @param location the node's reference to an external file or folder
     * @param access the node's public access level
     * @param owner the user that owns the newly created node
     * @param parent the parent node of the newly created node
     * @return a new node with the specified properties
     */
    VFSNode createNode(String name, String location, VFSNode.PublicAccess access, VFSUser owner, VFSNode parent) throws VFSException;
    
    /**
     * Restores a user with the specified id.  This method does
     * not invoke the persistence layer, but should be used by the
     * persistence layer in order to restore an object.
     * 
     * @param uid the user's id in an external authentication system
     * @return a restored user, with the specified id
     */
//    VFSUser restoreUser(String uid) throws VFSException;
//    
//    /**
//     * Restores a group with the specified name.  This method does
//     * not invoke the persistence layer, but should be used by the
//     * persistence layer in order to restore an object.
//     * 
//     * @param name the group's name
//     * @return a restored group, with the specified name
//     */
//    VFSGroup restoreGroup(String name) throws VFSException;
//    
//    /**
//     * Restores a node type with the specified properties.  
//     * This method does not invoke the persistence layer, 
//     * but should be used by the persistence layer in order 
//     * to restore an object.
//     * 
//     * @param name the node type's name
//     * @param description the node type's description
//     * @return a restored node type, with the specified properties
//     */
//    VFSNodeType restoreNodeType(String name, String description) throws VFSException;
//    
//    /**
//     * Restores a node with the specified properties.  
//     * This method does not invoke the persistence layer, 
//     * but should be used by the persistence layer in order 
//     * to restore an object.
//     * 
//     * @param name the node's name
//     * @param location the node's reference to an external file or folder
//     * @param createdOn the date the node was created on
//     * @param modifiedOn the date the node was last modified
//     * @param access the node's public access level
//     * @return a restored node, with the specified properties
//     */
//    VFSNode restoreNode(String name, String location, Date createdOn, Date modifiedOn, VFSNode.PublicAccess access) throws VFSException;
    
    /**
     * Removes potentially multiple users from the system, based on a filter.
     * 
     * @param filter the filter used to select users for removal
     */
    void removeUser(VFSFilter filter) throws VFSException;
    
    /**
     * Removes potentially multiple groups from the system, based on a filter.
     * 
     * @param filter the filter used to select groups for removal
     */
    void removeGroup(VFSFilter filter) throws VFSException;
    
    /**
     * Removes potentially multiple node types from the system, based on a filter.
     * 
     * @param filter the filter used to select node types for removal
     */
    void removeNodeType(VFSFilter filter) throws VFSException;
    
    /**
     * Removes potentially multiple nodes from the system, based on a filter.
     * 
     * @param filter the filter used to select nodes for removal
     */
    void removeNode(VFSFilter filter) throws VFSException;
    
    /**
     * Removes a user from the system.
     * 
     * @param user the user to be removed
     */
    void removeUser(VFSUser user) throws VFSException;
    
    /**
     * Removes a group from the system.
     * 
     * @param group the group to be removed
     */
    void removeGroup(VFSGroup group) throws VFSException;
    
    /**
     * Removes a node type from the system.
     * 
     * @param nodeType the node type to be removed
     */
    void removeNodeType(VFSNodeType nodeType) throws VFSException;
    
    /**
     * Removes a node from the system.
     * 
     * @param node the node to be removed
     */
    void removeNode(VFSNode node) throws VFSException;
    
}
